Skip to main content
Version: V11

VTT File Writer Node

The VTT File Writer node transforms structured timed data into WebVTT subtitle files for video captioning and accessibility. It converts millisecond timestamps to standard VTT time format and stores generated files in tenant-isolated temporary storage. The output files are compatible with HTML5 video players, media servers, and accessibility tools.

How It Works​

When the node executes, it reads an array of caption objects from the specified input variable, where each object contains start time, end time, and text content. The node processes these objects sequentially, converting millisecond timestamps into the standard WebVTT time format (HH:MM:SS.mmm), and assembles them into a properly formatted WebVTT file with the required header and structure.

The generated VTT file is saved to tenant-isolated temporary storage with a unique filename to prevent conflicts. The file path is stored in the specified output variable, making it available for downstream operations such as uploading to content management systems, attaching to video files, or serving to video players.

The node validates input data structure and skips any caption objects with missing required fields (startTime, endTime, or text), logging warnings for skipped items while continuing to process valid captions. This ensures robust file generation even when working with incomplete or inconsistent data sources.

Configuration Parameters​

Input Field​

Input Field (Text, Required): Workflow variable containing the array of caption objects.

Each object requires three properties: startTime (integer in milliseconds), endTime (integer in milliseconds), and text (string content). The array typically comes from transcription services, speech-to-text nodes, or custom data processing. Objects with missing required fields are skipped with warnings logged.

Example structure:

[
  {"startTime": 0, "endTime": 2500, "text": "Welcome to the video."},
  {"startTime": 2500, "endTime": 5000, "text": "This is the second caption."}
]

Output Field​

Output Field (Text, Required): Workflow variable where the generated file path is stored.

The output is a file path string pointing to the generated WebVTT file in tenant-isolated temporary storage. The path uses the format /temp/{tenantId}/vtt_{uuid}.vtt where the UUID ensures unique filenames. This path can be used by downstream nodes to upload, attach, or serve the file.

Common naming patterns: vtt_file_path, subtitle_file, caption_file_path, vtt_output.

Common Parameters​

This node supports common parameters shared across workflow nodes, including Logging Mode. For detailed information, see Common Parameters.

Best Practices​

  • Validate input data contains all required fields (startTime, endTime, text) before processing; objects with missing fields are skipped, potentially resulting in incomplete subtitle files
  • Timestamps must be in milliseconds rather than seconds for accurate time formatting
  • Sequential, non-overlapping timestamps (startTime < endTime, no caption overlap) ensure proper video player display
  • Combine with upload or file transfer nodes to move generated files from temporary storage to permanent locations
  • Descriptive variable names like video_subtitles_vtt improve workflow maintainability
  • For accessibility compliance, validate generated VTT files meet WCAG standards by testing with video players and screen readers

Limitations​

  • Temporary storage only: Generated VTT files are stored in temporary storage and may be cleaned up by system maintenance. Move files to permanent storage for long-term retention.
  • No file format validation: The node does not validate semantic correctness of caption text or timing logic beyond basic field presence. Overlapping or out-of-order timestamps are written as provided.
  • Millisecond precision required: Input timestamps must be in milliseconds. The node does not support other time units or automatic conversion.
  • No caption styling: The node generates basic WebVTT files without styling, positioning, or advanced VTT features. Custom styling requires post-processing.
  • Skipped invalid items: Caption objects missing required fields are silently skipped with warnings logged, which may result in incomplete subtitle files.
  • Single language only: The node generates single-language VTT files. Multi-language subtitle workflows require multiple node executions.
Did you find this article helpful?